= Moin Wiki Macros =

With the exception of the markup supported within FootNotes, the MoinWiki and CreoleWiki parsers have identical macro syntax and features. The contents of this MoinWiki page will yield similar results when copied to a CreoleWiki page.

Features that are not working correctly are marked with '''MOINTODO:'''

== Four Built-in Macros ==

There are four built-in macros.

=== TableOfContents ===

The number of levels in the table of contents can be limited by passing an integer parameter.

'''Markup:'''

{{{
<<TableOfContents(3)>>
}}}

'''Result:'''
<<TableOfContents(3)>>

See TOC floated to right.

=== FootNotes ===

'''Markup:'''

{{{
Footnotes can be placed by using the macro syntax.<<FootNote(A macro is enclosed in double angle brackets, and '''may''' have markup.)>>

By default footnotes are placed at the bottom of the page. Explicit placement of footnotes is accomplished by calling the macro without a parameter:

<<FootNote()>>

Subsequent footnotes<<FootNote(This footnote is placed at bottom of page by default.)>> will be numbered starting with 1 and placed at the bottom of the page by default.
}}}

'''Result:'''

Footnotes can be placed by using the macro syntax.<<FootNote(A macro is enclosed in double angle brackets, and '''may''' have markup.)>>

By default footnotes are placed at the bottom of the page. Explicit placement of footnotes is accomplished by calling the macro without a parameter:

<<FootNote()>>

Subsequent footnotes<<FootNote(This footnote is placed at bottom of page by default.)>> will be numbered starting with 1 and placed at the bottom of the page by default.

=== BR - Forced Line Break ===

'''Markup:'''

{{{
Use a BR macro <<BR>>to force a line break.
}}}

'''Result:'''

Use a BR macro <<BR>>to force a line break.

=== Include ===

'''Markup:'''

{{{
Include an image (very similar to transclusion):

<<Include(help-common/logo.png)>>

- - - - end of <Include(help-common/logo.png)> - - - -

Include all items with names beginning with "archive" within all namespaces. Any regex will work,
but first character must be "^". Name and Namespace are separate Whoosh index fields, attempts
to include a leading namespace will fail.

<<Include(^archive)>>

- - - - end of <Include(^archive)> - - - -

Include a page with a non-ascii name and a heading level 6 inside a comment. Click the "Comments"
link inside Item Views to show/hide the inclusion.

{{{{#!wiki comment/dashed
<<Include(help-en/StronaGłówna,My Favorite Page, 6)>>
}}}}

- - - - end of <Include(help-en/StronaGłówna,My Favorite Page, 6)> - - - -
}}}

'''Result:'''

Include an image (very similar to transclusion):

<<Include(help-common/logo.png)>>

- - - - end of <Include(help-common/logo.png)> - - - -

Include all items with names beginning with "archive" within all namespaces. Any regex will work,
but first character must be "^". Name and Namespace are separate Whoosh index fields, attempts
to include a leading namespace will fail.

<<Include(^archive)>>

- - - - end of <Include(^archive)> - - - -

Include a page with a non-ascii name and a heading level 6 inside a comment. Click the "Comments"
link inside Item Views to show/hide the inclusion.

{{{{#!wiki comment/dashed
<<Include(help-en/StronaGłówna,My Favorite Page, 6)>>
}}}}

- - - - end of <Include(help-en/StronaGłówna,My Favorite Page, 6)> - - - -

'''MOINTODO:''' Some of the moin 1.9 parameters documented in [[https://moinmo.in/HelpOnMacros/Include]] are not supported. These include: from, to, sort, items, skipitems, titlesonly, and editlink.

== Extension Macros from MoinMoin/macro/ ==

=== Anchor ===

Anchors are created (but invisible of course). Click [[MoinWikiMacros#anchorname|here]] to scroll the window to the anchor following '''Result''' below.

'''Markup:'''

{{{
<<Anchor(anchorname)>>
}}}

'''Result:'''

<<Anchor(anchorname)>>

=== Date ===

'''Markup:'''

{{{
<<Date()>>

<<Date(1434563755)>>

<<Date(2002-01-23T12:34:56)>>

Do this after <<Date()>> but before <<Date(2022-01-23T12:34:56)>>.
}}}

'''Result:'''

<<Date()>>

<<Date(1434563755)>>

<<Date(2002-01-23T12:34:56)>>

Do this after <<Date()>> but before <<Date(2022-01-23T12:34:56)>>.

=== DateTime ===

'''Markup:'''

{{{
<<DateTime()>>

<<DateTime(1434563755)>>

<<DateTime(2002-01-23T12:34:56)>>

Do this after <<DateTime()>> but before <<DateTime(2022-01-23T12:34:56)>>.
}}}

'''Result:'''

<<DateTime()>>

<<DateTime(1434563755)>>

<<DateTime(2002-01-23T12:34:56)>>

Do this after <<DateTime()>> but before <<DateTime(2022-01-23T12:34:56)>>.

=== FontAwesome ===

The FontAwesome macro displays any of the Font Awesome characters. See [[http://fontawesome.io/icons/|the Font Awesome site]] for a complete list.

The format of the macro is:

{{{
<<FontAwesome(classes,color,size)>>
}}}

The color and size parameters are optional.

 * color must be a hex digit color code of either 3 or 6 digits with a leading #:
   * #f00 or #F80000
 * size may be an unsigned decimal integer or float that will adjust the size of the character relative to the current font size.
   * 2 or 2.0 will create double the character size
   * .5 will create a character half the current size

In most cases, the class will consist of the single character name. If multiple classes are wanted, separate the names with spaces. Although the size parameter is more robust, the special Font Awesome "lg", "2x", "3x", and "4x" may be used. The "spin" class may be used for the spinner fonts.

Font awesome experts will know about the special "fa" class and the "fa-" name prefixes. It is acceptable, but not necessary to provide these.

'''Markup:'''

{{{
<<FontAwesome(thumbs-up,,2)>>  is identical to <<FontAwesome(fa fa-thumbs-up fa-2x)>>

<<FontAwesome(spinner spin,#f00)>>  is identical to <<FontAwesome(fa fa-spinner fa-spin,#f00)>>
}}}

'''Result:'''

<<FontAwesome(thumbs-up,,2)>>  is identical to <<FontAwesome(fa fa-thumbs-up fa-2x)>>

<<FontAwesome(spinner spin,#f00)>>  is identical to <<FontAwesome(fa fa-spinner fa-spin,#f00)>>

=== GetText ===

Loads I18N texts. If this browser is set to German/Deutsch the macro output will be: Einstellungen ("Settings" is included in the translation files).

'''Markup:'''

{{{
<<GetText(Settings)>>
}}}

'''Result:'''

<<GetText(Settings)>>

=== GetVal ===

For GetVal to work, there must be either a ConfigDict or WikiDict defined (see config docs). This example depends upon an item named [[WikiDict]] having specific metadata. See configuration docs for details.

'''Markup:'''

{{{
<<GetVal(help-en/WikiDict,var1)>>
}}}

'''Result:'''

<<GetVal(help-en/WikiDict,var1)>>

=== Icon ===

The Icon macro displays an icon. The complete list of available icons are listed within [[MoinWikiMacros/Icons]].

'''Markup:'''

{{{
Here is the moin icon: <<Icon(moin-logo.png)>>
}}}

'''Result:'''

Here is the moin icon: <<Icon(moin-logo.png)>>

=== MailTo ===

The MailTo macro exports different markup when the user is logged in.

'''Markup:'''

{{{
<<MailTo(user AT example DOT org)>>

<<MailTo(user AT example DOT org, write me)>>
}}}

'''Result:'''

<<MailTo(user AT example DOT org)>>

<<MailTo(user AT example DOT org, write me)>>


=== ItemList ===

This section is partitioned into subsections, one for each ItemPageList parameter.

Most of the examples below search for descendents under the top-level "OtherTextItems"
item, the only sample-wiki item that contains a significant number of descendents.


===== The "item" parameter =====


'''Markup:'''

{{{
The default is the current page:

<<ItemList()>>

An empty string gives the wiki root.

<<ItemList(item="")>>

An item that does not exist (potentially due to ACLs) produces a warning:

<<ItemList(item="DoesNotExist")>>

An item that has no children (potentially due to ACLs) produces a message stating so:

<<ItemList(item="Home/subitem")>>
}}}

'''Result:'''

The default is the current page:

<<ItemList()>>

An empty string gives the wiki root. The output is suppressed here because it can produce a very long result list.

An item that does not exist (potentially due to ACLs) produces a warning:

<<ItemList(item="DoesNotExist")>>

An item that has no children (potentially due to ACLs) produces a message stating so:

<<ItemList(item="Home/subitem")>>


===== The "ordered" parameter =====

Lists are unordered (ordered="False") by default (see above for examples).

'''Markup:'''

{{{

An ordered list:

<<ItemList(item="help-en/OtherTextItems", ordered="True")>>
}}}

'''Result:'''

An ordered list:

<<ItemList(item="help-en/OtherTextItems", ordered="True")>>


===== The "startswith" parameter =====

Search for items where the descendent's name begins with the letter 'P'.  Note that using
the "startswith" parameter is more efficient than the equivalent "regex" expression:

'''Markup:'''

{{{
<<ItemList(item="help-en/OtherTextItems", startswith="P")>>
}}}

'''Result:'''

<<ItemList(item="help-en/OtherTextItems", startswith="P")>>


===== The "regex" parameter =====

'''Markup:'''

{{{
Those items containing the string "Text" anywhere in the full path name:

<<ItemList(item="OtherTextItems", regex="Text")>>

Those items containing the string "Text" only in the descendent's name:

<<ItemList(item="OtherTextItems", regex="^.*/.*Text")>>

Those items containing a vowel as the 3rd-to-last character:

<<ItemList(item="OtherTextItems", regex="(?i)[aeiou].{2}$")>>
}}}

'''Result:'''

Those items containing the string "Text" anywhere in the full path name:

<<ItemList(item="OtherTextItems", regex="Text")>>

Those items containing the string "Text" only in the descendent's name:

<<ItemList(item="OtherTextItems", regex="^.*/.*Text")>>

Those items containing a vowel as the 3rd-to-last character:

<<ItemList(item="OtherTextItems", regex="(?i)[aeiou].{2}$")>>


===== The "display" parameter =====

All of the following examples display just the "PlainText" item.

'''Markup:'''

{{{
Displayed using "FullPath" (the default, see examples above):

<<ItemList(item="OtherTextItems", regex="PlainText", display="FullPath")>>

Displayed using "FullPath":

<<ItemList(item="OtherTextItems", regex="PlainText", display="ChildPath")>>

Displayed using "ChildName":

<<ItemList(item="OtherTextItems", regex="PlainText", display="ChildName")>>

Displayed using "UnCameled":

<<ItemList(item="OtherTextItems", regex="PlainText", display="UnCameled")>>
}}}

'''Result:'''

Displayed using "FullPath":

<<ItemList(item="OtherTextItems", regex="PlainText", display="FullPath")>>

Displayed using "FullPath":

<<ItemList(item="OtherTextItems", regex="PlainText", display="ChildPath")>>

Displayed using "ChildName":

<<ItemList(item="OtherTextItems", regex="PlainText", display="ChildName")>>

Displayed using "UnCameled":

<<ItemList(item="OtherTextItems", regex="PlainText", display="UnCameled")>>

=== MonthCalendar ===

The MonthCalendar macro is for those who need a calendar wiki integration or want to use MoinMoin as a Personal Information Manager.

'''Markup:'''

{{{
<<MonthCalendar(item,year,month,month_offset,fixed_height,anniversary)>>
}}}

For more details see [[MoinWikiMacros/MonthCalendar]]

=== RandomItem ===

'''Markup:'''

{{{
One random item:

<<RandomItem()>>

Five random items:

<<RandomItem(5)>>
}}}

'''Result:'''

One random item:

<<RandomItem()>>

Five random items:

<<RandomItem(5)>>

=== Verbatim ===

'''Markup:'''

{{{
Verbatim macro Returns `same` __text__ '''as''' entered

<<Verbatim(Returns `same` __text__ '''as''' entered)>>

<<Verbatim(<script>alert(1);</script>)>>
}}}

'''Result:'''

Verbatim macro Returns `same` __text__ '''as''' entered

<<Verbatim(Returns `same` __text__ '''as''' entered)>>

<<Verbatim(<script>alert(1);</script>)>>
